home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Diamond Collection / The Diamond Collection (Software Vault)(Digital Impact).ISO / cdr27 / cal33.zip / CAL.DOC < prev    next >
Text File  |  1995-01-15  |  8KB  |  175 lines
  1. CAL     display a calendar      version 3.1
  2.  
  3. SYNOPSIS
  4.  
  5.         cal [options] [[num_month] year]     (numerical arguments)
  6.         cal [options] [word_month] [year]    (verbal month argument)
  7.  
  8. DESCRIPTION
  9.  
  10. Cal is an enhanced version of the unix cal command.  It is compatible to
  11. the unix version in that it uses the same input arguments and its output
  12. may be piped or redirected anywhere.
  13.  
  14. Cal displays a calendar for a specified year, a specified month and year,
  15. or for the current date.  By default, it displays a calendar for the current
  16. system-date month, with the current day hilighted.  It correctly handles the
  17. transition from the Julian to Gregorian calendars in September 1752.
  18.  
  19. ARGUMENTS
  20.  
  21. A verbally-specified month may be entered without specifying a year in the
  22. argument list; however, a single numerical argument will be interpreted as
  23. a year.  Only the first 3 characters of the month name are significant for
  24. a verbally-specified month.  The command `cal 10' refers to 10 AD, not
  25. October, and not 1910.
  26.  
  27. The options are explained more fully in the ENHANCEMENTS sections below.
  28. The available options are:
  29.  
  30.  -nod[ata]              - Do not try to read any appointment data file.
  31.  -d[ata-file]=filename  - Read appointments from `filename'
  32.                           (default appointment data filename is cal.dat).
  33.                           You may use -d to 8 times, in a commandline,
  34.                           to specify multiple data file names.
  35.  -f[uture]              - If current month is displayed, then show only
  36.                           future appointments from the appointment file,
  37.                           not appointments that are past.
  38.                           NOTE:  This switch was -d in previous versions.
  39.  -e[urope]              - Use European format (first weekday is Monday).
  40.  -m[axappts]            - Maximum number of appointments to display.
  41.                           Minimum is 8, maximum is 50, default is 24.
  42.  -noc[olor]             - Inhibit the use of colors.
  43.  -c[olor-file]=filename - Read color definitions from `filename'
  44.                           (default color filename is cal.col).
  45.  
  46. COMMAND EXAMPLES
  47.  
  48.         cal -f -d=my_dates  display the current month and future
  49.                             appointments defined in file `my_dates'
  50.         cal 1996        display the entire year of 1996
  51.         cal 9 1752      display the month of September 1752
  52.         cal sep 1752    same as above
  53.         cal January     display January of the current year
  54.         cal help        help message displayed for unrecognized arguments
  55.  
  56. ENHANCEMENTS OVER STANDARD `CAL' COMMAND - the cal.dat file
  57.  
  58. If displaying the single-month format, cal will look for a file called
  59. cal.dat (or whatever you specify with the -d option) in the current
  60. directory and then in cal's directory of origin.  If found, cal will read
  61. the file, looking for special date descriptions for that month which will
  62. be displayed to the right of the calendar.  By default, up to 24
  63. appointments (number may be chaned with -m) may be displayed per month.
  64. If the current date happens to fall on one of these special dates, it will
  65. be flagged by an asterisk.  If there is room, appointments for the next
  66. month may also be displayed (next month's dates having definitions like
  67. "2nd Thursday" will be skipped).  The special date descriptions specified
  68. in cal.dat are single lines, formatted as follows:
  69.  
  70. YYYY MM DD NW xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  71.  
  72. Where
  73.   YYYY is the year,
  74.   MM is the month (01 - 12),
  75.   DD is the day (00 if the NW field is used),
  76.   NW is the weekday-of-month code (00 if the DD field is used)
  77.   xxxx... is the description; it will be truncated as necessary to fit
  78.  
  79. The data MUST occupy the character fields as shown.  If YYYY is specified
  80. as -999, the month and day are assumed to be annual events such as holidays,
  81. and the description will be displayed for any year.  If MM is specified as
  82. -9, the day is assumed to be a monthly event for the specified year.  In the
  83. weekday-of-month code NW, N signifies on which weekday W the special date
  84. occurs.  For example, 31 indicates the third sunday.  Values of W range from
  85. 1 to 7, for Sunday to Saturday, respectively.  A value of 9 for N indicates
  86. "last" as in 95 for "last thursday."
  87.  
  88. You can display birthdays and anniversaries by putting the year of birth
  89. (or other special event) inside brackets or braces, in the description.
  90. This number is converted to the number of years since the year you indicate.
  91. If brackets [] are used, they will be displayed around this number.  If
  92. braces {} are used, they will not be displayed, but the number will have
  93. an ordinal suffix, as in 21st, 32nd, 43rd, 54th, etc.  If the number in
  94. brackets or braces is greater than the current year, the number will be
  95. displayed unchanged (and braces WILL be displayed).  Example:
  96. "Alex's {1961} birthday" will display as "Alex's 34th birthday" (if the
  97. current year is 1995).
  98.  
  99. NOTE:  If cal is invoked with the -europe switch, then the W values 1-7
  100. denote Monday(1) to Sunday(7) rather than Sunday(1) to Saturday(7).
  101.  
  102. A line in cal.dat must start with -999 or a 4-digit number to be considered
  103. as data.  The data lines may be in any order.  All these appointments will
  104. be displayed in chronological order, regardless of the ordering in the
  105. appointment data file.
  106.  
  107. The -f commandline switch causes any date description older than today's
  108. date to be ignored, thereby giving room for other descriptions with future
  109. dates to be displayed.  As time progresses through the month, old
  110. descriptions are discarded and newer ones are used.  The -f switch affects
  111. only the display for the current month, and not other months.
  112.  
  113. ENHANCEMENTS SPECIFIC TO MS-DOS and OS/2
  114.  
  115. Under MSDOS or OS/2, commandline arguments may begin with a '/' instead of
  116. a '-' character.  It works either way.
  117.  
  118. Cal modifies the display attributes behind its output in order to display
  119. the calendar in attractive colors.  Display manipulation is not done if
  120. cal's output is redirected to a file.  When cal starts up, it looks for a
  121. file called cal.col (or whatever you specify with the -c option), first
  122. in the current directory, and then in cal's originating directory.
  123. The colors have their own defaults if the file is not found.
  124.  
  125. Example of a color definition file:
  126.  
  127. 15 02   video colors for month name
  128. 01 03   video colors for weekday header
  129. 07 01   video colors for normal calendar days
  130. 13 01   video colors for sundays
  131. 14 02   video colors for current day
  132. 07 06   background color for yearly calendar (the space between months)
  133. 11 00   video colors for special day descriptions
  134. 12 08   video colors for asterisk indicating that a description=today
  135.  
  136. FG BG
  137.  
  138. Color definitions must appear as above, as a two-character field for the
  139. foreground color, followed by a space, folowed by a two-character field for
  140. the background color.  The color definitions must start on the first line,
  141. and must not contain blank lines.  Comments may appear after the second
  142. field, provided that the total line length does not exceed 80 characters.
  143.  
  144. Possible colors:
  145.  
  146.         black           0
  147.         blue            1
  148.         green           2
  149.         cyan            3
  150.         red             4
  151.         violet          5
  152.         orange          6
  153.         light gray      7
  154.  
  155.         dark gray       8
  156.         bright blue     9
  157.         bright green    10
  158.         bright cyan     11
  159.         bright red      12
  160.         bright violet   13
  161.         yellow          14
  162.         white           15
  163.  
  164. Specifying a background color from 8 to 15 will result in a background
  165. color of 0 to 7, with flashing text.
  166.  
  167. AUTHOR
  168.  
  169.         Alex Matulich  -  matulich_a@seaa.navsea.navy.mil
  170.  
  171.         ...with enhancements and modifications by other contributors.
  172.  
  173.         (c) 1995 by Unicorn Research Corporation.  All rights reserved.
  174.         Inspired by an Amiga program by Gary L. Brant.
  175.